Повний посібник з дистрибуції пакетів Python через PyPI, що охоплює найкращі практики керування версіями, інструменти та робочі процеси для розробників.
Дистрибуція пакетів Python: публікація на PyPI та керування версіями
Розгалужена екосистема Python живиться величезною колекцією пакетів, легкодоступних через Python Package Index (PyPI). Цей посібник надає вичерпний огляд того, як розповсюджувати власні пакети Python через PyPI, забезпечуючи їх доступність для розробників у всьому світі. Ми розглянемо основні інструменти, найкращі практики керування версіями та робочі процеси для створення та публікації високоякісних пакетів Python.
Навіщо розповсюджувати свій пакет Python?
Розповсюдження вашого пакета Python надає численні переваги:
- Діліться своєю роботою: Дозволяє іншим розробникам легко повторно використовувати ваш код, сприяючи співпраці та інноваціям. Уявіть, як глобальна команда використовує ваші спеціалізовані інструменти для аналізу даних, створені на Python.
- Керування залежностями: Спрощує процес керування залежностями в інших проєктах. Ваш пакет можна встановити однією командою разом з усіма його залежностями.
- Внесок у відкритий код: Дає змогу робити внесок у спільноту відкритого коду та отримувати визнання за свою роботу. Багато критично важливих програмних компонентів є пакетами з відкритим кодом, які підтримуються розробниками з усього світу.
- Контроль версій та оновлення: Забезпечує структурований спосіб керування версіями, випуску оновлень та виправлення помилок. Це гарантує, що користувачі завжди мають доступ до останньої та найнадійнішої версії вашого пакета.
- Просте встановлення: Спрощує встановлення для користувачів за допомогою
pip install ваша-назва-пакета.
Основні інструменти для дистрибуції пакетів Python
Кілька інструментів є важливими для створення та розповсюдження пакетів Python:
- setuptools: Широко використовувана бібліотека для визначення метаданих пакета, включаючи назву, версію, залежності та точки входу. Це стандарт де-факто для пакування проєктів Python.
- wheel: Формат дистрибутива, що забезпечує ефективніший та надійніший процес встановлення порівняно з дистрибутивами з вихідним кодом. Wheel — це попередньо зібрані дистрибутиви, які можна встановити без компіляції.
- twine: Інструмент для безпечного завантаження вашого пакета на PyPI. Twine шифрує ваші облікові дані та дані пакета під час передачі, захищаючи від прослуховування та атак «людина посередині».
- venv/virtualenv: Це інструменти для створення ізольованих середовищ Python. Використання віртуальних середовищ є вирішальним для керування залежностями та уникнення конфліктів між різними проєктами.
Налаштування вашого проєкту
Перш ніж ви зможете розповсюджувати свій пакет, вам потрібно правильно структурувати свій проєкт.
Приклад структури проєкту
my_package/ ├── my_package/ │ ├── __init__.py │ ├── module1.py │ └── module2.py ├── tests/ │ ├── __init__.py │ ├── test_module1.py │ └── test_module2.py ├── README.md ├── LICENSE ├── setup.py └── .gitignore
Пояснення:
- my_package/: Основна директорія, що містить вихідний код вашого пакета.
- my_package/__init__.py: Робить директорію `my_package` пакетом Python. Він може бути порожнім або містити код ініціалізації.
- my_package/module1.py, my_package/module2.py: Ваші модулі Python, що містять фактичний код.
- tests/: Директорія, що містить ваші юніт-тести. Важливо писати тести для забезпечення якості та надійності вашого пакета.
- README.md: Файл Markdown, що містить опис вашого пакета, інструкції з використання та іншу відповідну інформацію. Це часто перше, що користувачі бачать на PyPI.
- LICENSE: Файл, що містить ліцензію, за якою розповсюджується ваш пакет (наприклад, MIT, Apache 2.0, GPL). Вибір відповідної ліцензії є важливим для визначення того, як інші можуть використовувати ваш код.
- setup.py: Основний конфігураційний файл, що визначає метадані вашого пакета та інструкції зі збірки.
- .gitignore: Визначає файли та директорії, які Git повинен ігнорувати (наприклад, тимчасові файли, артефакти збірки).
Створення файлу `setup.py`
Файл `setup.py` — це серце дистрибуції вашого пакета. Він містить метадані про ваш пакет та інструкції для його збірки та встановлення. Ось приклад:
import setuptools
with open("README.md", "r") as fh:
long_description = fh.read()
setuptools.setup(
name="my_package", # Замініть на назву вашого пакета
version="0.1.0",
author="Your Name", # Замініть на ваше ім'я
author_email="your.email@example.com", # Замініть на вашу електронну пошту
description="Невеликий приклад пакета",
long_description=long_description,
long_description_content_type="text/markdown",
url="https://github.com/yourusername/my_package", # Замініть на URL вашого репозиторію
packages=setuptools.find_packages(),
classifiers=[
"Programming Language :: Python :: 3",
"License :: OSI Approved :: MIT License",
"Operating System :: OS Independent",
],
python_requires='>=3.6',
install_requires=[
"requests", # Приклад залежності
],
)
Пояснення:
- name: Назва вашого пакета, яка буде використовуватися на PyPI. Оберіть унікальну та описову назву.
- version: Номер версії вашого пакета. Дотримуйтесь семантичного версіонування (див. нижче).
- author, author_email: Ваше ім'я та адреса електронної пошти.
- description: Короткий опис вашого пакета.
- long_description: Довший, більш детальний опис, зазвичай зчитується з вашого файлу `README.md`.
- long_description_content_type: Вказує формат вашого довгого опису (наприклад, "text/markdown").
- url: URL-адреса домашньої сторінки вашого пакета (наприклад, репозиторій GitHub).
- packages: Список пакетів для включення у ваш дистрибутив. `setuptools.find_packages()` автоматично знаходить усі пакети у вашому проєкті.
- classifiers: Метадані, які допомагають користувачам знаходити ваш пакет на PyPI. Виберіть відповідні класифікатори зі списку Trove Classifiers. Розгляньте можливість включення класифікаторів для підтримуваних версій Python, операційних систем та ліцензій.
- python_requires: Вказує мінімальну версію Python, необхідну для використання вашого пакета.
- install_requires: Список залежностей, які вимагає ваш пакет. Ці залежності будуть автоматично встановлені під час встановлення вашого пакета.
Керування версіями: семантичне версіонування
Семантичне версіонування (SemVer) — це широко поширена схема версіонування, яка забезпечує чіткий та послідовний спосіб повідомлення про характер змін у вашому пакеті.
Номер версії SemVer складається з трьох частин: MAJOR.MINOR.PATCH.
- MAJOR: Збільшується, коли ви робите несумісні зміни в API. Це вказує на значну зміну, яка може вимагати від користувачів оновлення їхнього коду.
- MINOR: Збільшується, коли ви додаєте функціональність зворотно сумісним чином. Це означає нові можливості або покращення, які не ламають існуючий код.
- PATCH: Збільшується, коли ви робите зворотно сумісні виправлення помилок. Це для невеликих виправлень, які не додають нових функцій і не ламають існуючу функціональність.
Приклади:
- 1.0.0: Початковий випуск.
- 1.1.0: Додано нову функцію без порушення існуючого коду.
- 1.0.1: Виправлено помилку у випуску 1.0.0.
- 2.0.0: Зроблено несумісні зміни в API.
Використання SemVer допомагає користувачам зрозуміти вплив оновлення до нової версії вашого пакета.
Збірка вашого пакета
Після того, як ви налаштували файл `setup.py`, ви можете зібрати свій пакет.
- Створіть віртуальне середовище: Наполегливо рекомендується створити віртуальне середовище для ізоляції залежностей вашого пакета. Використовуйте `python3 -m venv .venv` (або `virtualenv .venv`), а потім активуйте його (`source .venv/bin/activate` на Linux/macOS, `.venv\Scripts\activate` на Windows).
- Встановіть залежності для збірки: Виконайте `pip install --upgrade setuptools wheel`.
- Зберіть пакет: Виконайте `python setup.py sdist bdist_wheel`. Ця команда створює два файли дистрибутива в директорії `dist`: дистрибутив з вихідним кодом (sdist) та дистрибутив wheel (bdist_wheel).
Дистрибутив `sdist` містить ваш вихідний код і файл `setup.py`. `bdist_wheel` — це попередньо зібраний дистрибутив, який можна встановити швидше.
Публікація вашого пакета на PyPI
Перш ніж опублікувати свій пакет, вам потрібно створити обліковий запис на PyPI (https://pypi.org/) та створити API-токен. Цей токен буде використовуватися для автентифікації ваших завантажень.
- Зареєструйтеся на PyPI: Перейдіть на https://pypi.org/account/register/ і створіть обліковий запис.
- Створіть API-токен: Перейдіть на https://pypi.org/manage/account/, прокрутіть до розділу "API tokens" і створіть новий токен. Зберігайте цей токен у безпечному місці, оскільки він знадобиться вам для завантаження пакета.
- Встановіть Twine: Виконайте `pip install twine`.
- Завантажте ваш пакет: Виконайте `twine upload dist/*`. Вас попросять ввести ім'я користувача (
__token__) та пароль (API-токен, який ви створили).
Важлива примітка щодо безпеки: Ніколи не комітьте ваш API-токен у свій репозиторій. Зберігайте його в безпечному місці та використовуйте змінні середовища або інші безпечні методи для доступу до нього під час процесу завантаження.
Тестування встановлення вашого пакета
Після публікації вашого пакета важливо перевірити, чи він може бути встановлений правильно.
- Створіть нове віртуальне середовище: Це гарантує, що ви тестуєте встановлення в чистому середовищі.
- Встановіть ваш пакет: Виконайте `pip install ваша-назва-пакета`.
- Імпортуйте та використовуйте ваш пакет: В інтерпретаторі Python імпортуйте ваш пакет і переконайтеся, що він працює, як очікувалося.
Безперервна інтеграція та безперервне розгортання (CI/CD)
Щоб автоматизувати процес збірки, тестування та публікації вашого пакета, ви можете використовувати інструменти CI/CD, такі як GitHub Actions, GitLab CI або Travis CI.
Ось приклад робочого процесу GitHub Actions, який збирає та публікує ваш пакет на PyPI:
name: Publish to PyPI
on:
release:
types: [published]
jobs:
publish:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Set up Python 3.x
uses: actions/setup-python@v2
with:
python-version: 3.x
- name: Install dependencies
run: |
python -m pip install --upgrade pip
pip install setuptools wheel twine
- name: Build package
run: python setup.py sdist bdist_wheel
- name: Publish package to PyPI
run: |
twine upload dist/* \
-u __token__ \
-p ${{ secrets.PYPI_API_TOKEN }}
Пояснення:
- Цей робочий процес запускається, коли на GitHub публікується новий реліз.
- Він завантажує код, налаштовує Python, встановлює залежності, збирає пакет і завантажує його на PyPI.
secrets.PYPI_API_TOKEN— це секрет GitHub, у якому зберігається ваш API-токен PyPI. Вам потрібно налаштувати цей секрет у налаштуваннях вашого репозиторію GitHub.
Найкращі практики для дистрибуції пакетів Python
- Пишіть вичерпну документацію: Додайте детальний файл `README.md`, а також документацію API, використовуючи інструменти, такі як Sphinx. Чітка та повна документація є вирішальною для того, щоб ваш пакет був простим у використанні.
- Пишіть юніт-тести: Ретельно тестуйте свій код, щоб забезпечити його якість та надійність. Використовуйте фреймворки для тестування, такі як pytest або unittest.
- Дотримуйтесь настанов стилю PEP 8: Дотримуйтесь посібника зі стилю Python Enhancement Proposal 8 (PEP 8), щоб забезпечити послідовний та читабельний код.
- Використовуйте ліцензію: Оберіть відповідну ліцензію з відкритим кодом, щоб вказати, як інші можуть використовувати ваш код.
- Підтримуйте свої залежності в актуальному стані: Регулярно оновлюйте залежності вашого пакета, щоб отримувати виправлення помилок, патчі безпеки та нові функції.
- Використовуйте віртуальне середовище: Завжди розробляйте та тестуйте свій пакет у віртуальному середовищі для ізоляції залежностей.
- Враховуйте інтернаціоналізацію (i18n) та локалізацію (l10n): Якщо ваш пакет обробляє текст або дані, що відображаються користувачеві, подумайте про його адаптацію до різних мов та регіонів. Це розширює вашу потенційну базу користувачів у всьому світі. Інструменти, такі як Babel, можуть допомогти в цьому.
- Обробляйте різні часові пояси та валюти: Якщо ваш пакет працює з датами, часом або фінансовими транзакціями, пам'ятайте про різні часові пояси та валюти по всьому світу. Використовуйте відповідні бібліотеки та API для коректної обробки цих складнощів.
- Надавайте чіткі повідомлення про помилки: Пишіть інформативні повідомлення про помилки, які допомагають користувачам зрозуміти, що пішло не так і як це виправити. Перекладайте ці повідомлення про помилки різними мовами, якщо це можливо.
- Дбайте про доступність: Враховуйте користувачів з обмеженими можливостями при розробці інтерфейсу та документації вашого пакета. Дотримуйтесь настанов щодо доступності, щоб ваш пакет був зручним для всіх.
Просунуті теми
- Пакети просторів імен: Дозволяють розділити один пакет Python на кілька директорій або навіть на кілька дистрибутивів.
- Точки входу: Дозволяють визначати функції або класи, які можна викликати з інших пакетів або з командного рядка.
- Файли даних: Дозволяють включати у ваш дистрибутив файли, що не є кодом Python (наприклад, файли даних, конфігураційні файли).
- Умовні залежності: Дозволяють вказувати залежності, які потрібні лише за певних умов (наприклад, для певної операційної системи).
Висновок
Розповсюдження вашого пакета Python на PyPI — це чудовий спосіб поділитися своєю роботою зі світом та зробити внесок в екосистему Python. Дотримуючись кроків та найкращих практик, викладених у цьому посібнику, ви зможете створювати та публікувати високоякісні пакети Python, які легко встановлювати, використовувати та підтримувати. Не забувайте надавати пріоритет чіткій документації, ретельному тестуванню та послідовному керуванню версіями для забезпечення успіху вашого пакета.